<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>Textual Inter</title>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
		<meta name="viewport" content="width=device-width initial-scale=1">
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<meta http-equiv="Content-Language" content="en-gb">

<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
		
	</head>
	<body class="commentary-font">
		<nav role="navigation">
		<h1><a href="../index.html"><img src="../docs-assets/Inform.png" height=72> </a></h1>
<ul><li><a href="../index.html">home</a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="../structure.html">structure</a></li>
<li><a href="../inbuildn.html">inbuild</a></li>
<li><a href="../inform7n.html">inform7</a></li>
<li><a href="../intern.html">inter</a></li>
<li><a href="../services.html">services</a></li>
<li><a href="../secrets.html">secrets</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="../inblorbn.html">inblorb</a></li>
<li><a href="../inform6.html">inform6</a></li>
<li><a href="../inpolicyn.html">inpolicy</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="../extensions.html">extensions</a></li>
<li><a href="../kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=0> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="https://github.com/ganelson/inweb"><img src="../docs-assets/github.png" height=0> inweb</a></li>
<li><a href="https://github.com/ganelson/intest"><img src="../docs-assets/github.png" height=0> intest</a></li>
</ul>
		</nav>
		<main role="main">
		<!-- Weave of 'Textual Inter' generated by inweb -->
<div class="breadcrumbs">
    <ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inter</a></li><li><a href="index.html#M">Manual</a></li><li><b>Textual Inter</b></li></ul></div>
<p class="purpose">A specification of the inter language, as written out in text file form.</p>

<ul class="toc"><li><a href="M-ti.html#SP1">&#167;1. A manual of a sort</a></li><li><a href="M-ti.html#SP3">&#167;3. Outside even main</a></li></ul><hr class="tocbar">

<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. A manual of a sort.</b>In its textual form, Inter could conceivably be used as a programming
language, albeit a low-level and verbose one, and this section is a brief
manual for that language. But the real purpose of Inter is to assist testing
and debugging of the Inform tool-chain. We can write test cases in textual
Inter to see if inter works; or we can write out memory inter to the
debugging log to see if inform7 works.
</p>

<p class="commentary">A textual inter file is a UTF-8 encoded text file which conventionally takes
the file extension ".intert". Here is an example, the test case <span class="extract"><span class="extract-syntax">Hello</span></span>:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">package</span><span class="plain-syntax"> main _plain</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">package</span><span class="plain-syntax"> Main _code</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">code</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">inv</span><span class="plain-syntax"> </span><span class="function-syntax">!enableprinting</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">inv</span><span class="plain-syntax"> </span><span class="function-syntax">!print</span>
<span class="plain-syntax">                </span><span class="reserved-syntax">val</span><span class="plain-syntax"> </span><span class="string-syntax">"Hello, world.\n"</span>
</pre>
<p class="commentary">Some basic characteristics of textual Inter can be seen at a glance. It's line-based:
each line makes a single use of a "construct" like <span class="extract"><span class="extract-syntax">package</span></span> or <span class="extract"><span class="extract-syntax">code</span></span>. Lines
can be of arbitrary length. A line beginning with a <span class="extract"><span class="extract-syntax">#</span></span> (in column 1) is
a comment, and blank lines are ignored.
</p>

<p class="commentary">As in Python, indentation from the left margin is highly significant, and
must be in the form of tab characters.
</p>

<p class="commentary">Most identifiers consist of a string of one or more English upper or lower
case letters, underscores, or digits, except that it must not begin with
a digit. Identifier lengths are unlimited. A few identifiers of special sorts
begin with a special character to mark them out as special: <span class="extract"><span class="extract-syntax">!enableprinting</span></span>,
for example, is a "primitive", marked with a <span class="extract"><span class="extract-syntax">!</span></span>.
</p>

<p class="commentary">A convention followed in Inter code generated by Inform is that many identifiers
have the form <span class="extract"><span class="extract-syntax">P_Name</span></span>, where <span class="extract"><span class="extract-syntax">P</span></span> is some prefix letter showing what sort of
thing is referred to: for example, variables begin with <span class="extract"><span class="extract-syntax">V</span></span>, instances with <span class="extract"><span class="extract-syntax">I</span></span>,
properties with <span class="extract"><span class="extract-syntax">P</span></span>, and so on. This is all done only for clarity, and is not
part of the Inter specification.
</p>

<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>The main organising idea of Inter is the "package". Each program is a nested
hierarchy of packages, and each package has both a name and a "package type".
In the <span class="extract"><span class="extract-syntax">Hello</span></span> example, an outer package called <span class="extract"><span class="extract-syntax">main</span></span>, of type <span class="extract"><span class="extract-syntax">_plain</span></span>,
holds only a inner package called <span class="extract"><span class="extract-syntax">Main</span></span>, of type <span class="extract"><span class="extract-syntax">_code</span></span>.
</p>

<p class="commentary">In fact, every program must contain just one outermost package, called <span class="extract"><span class="extract-syntax">main</span></span>,
which has to have type <span class="extract"><span class="extract-syntax">_plain</span></span>, so that is unsurprising.
</p>

<p class="commentary">Packages of type <span class="extract"><span class="extract-syntax">_code</span></span> are functions. A program is not required to contain any
functions at all, and even if it does, it is not required to contain one called
<span class="extract"><span class="extract-syntax">Main</span></span>. For example, the Inter program into which BasicInformKit is compiled
does not provide a <span class="extract"><span class="extract-syntax">Main</span></span>, and we could imagine kits which provided, say, only
some variables and arrays. But if we want a program to compile and run in a
stand-alone way, then it needs a <span class="extract"><span class="extract-syntax">Main</span></span> function as a place to begin running.
</p>

<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. Outside even main.</b>Though this does not happen in the <span class="extract"><span class="extract-syntax">Hello</span></span> example, a handful of instructions
can appear at the top of the program, outside even <span class="extract"><span class="extract-syntax">main</span></span>. These really just
define conventions used in the rest of the program, rather than describing
what the program does, and that is why they are on the outside.
</p>

<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. </b><span class="extract"><span class="extract-syntax">version NUMBER</span></span> indicates that the file was written in that version of
the Inter language. <span class="extract"><span class="extract-syntax">NUMBER</span></span> is a semantic version number, and it forces
<a href="index.html" class="internal">inter</a> to reject the file if the version of the Inter specification
understood by <a href="index.html" class="internal">inter</a> is not compatible with the one in the file. (Note
that this about the version of the specification, not the version of <a href="index.html" class="internal">inter</a>
as a program.)
</p>

<p class="commentary">See <a href="../bytecode-module/1-tiv.html" class="internal">The Inter Version (in bytecode)</a> for more on the significance of this.
</p>

<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b><span class="extract"><span class="extract-syntax">pragma TARGET "WHATEVER"</span></span> does not change the meaning of the inter file;
it simply provides pragmatic advice to the eventual compiler of code
generated from this file. <span class="extract"><span class="extract-syntax">TARGET</span></span> indicates the context for which this
is intended.
</p>

<p class="commentary">At present Inform 7 uses this to pass on ICL (Inform Command Language)
commands to Inform 6, such as memory settings or command-line switches.
For example,
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">pragma</span><span class="plain-syntax"> Inform6 </span><span class="string-syntax">"$MAX_LABELS=200000"</span>
</pre>
<p class="commentary">When a program containing this instruction is generated to C, say, then this
is ignored completely. And in fact, now that Inform has adopted Inform 6.36 as
its preferred copy of I6, memory settings have become unnecessary and are
ignored by I6 anyway, so even this use of <span class="extract"><span class="extract-syntax">pragma</span></span> may yet disappear.
</p>

<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>&#167;6. </b><span class="extract"><span class="extract-syntax">packagetype _NAME</span></span> declares that <span class="extract"><span class="extract-syntax">_NAME</span></span> can be used as a package type.
It's actually unnecessary to write this explicitly, which is why the <span class="extract"><span class="extract-syntax">Hello</span></span>
example did not begin with:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">packagetype</span><span class="plain-syntax"> _plain</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">packagetype</span><span class="plain-syntax"> _code</span>
</pre>
<p class="commentary">If the program creates, say, <span class="extract"><span class="extract-syntax">package MOMA _museum</span></span>, then the necessary
package type instruction <span class="extract"><span class="extract-syntax">packagetype _museum</span></span> will be inferred automatically.
Nevertheless, it's valid to spell this out.
</p>

<p class="commentary">All package types have names beginning with an underscore <span class="extract"><span class="extract-syntax">_</span></span>. Authors of
Inter programs are free to choose any types they like, and Inform tends to
use semantically meaningful type names like <span class="extract"><span class="extract-syntax">_adjective</span></span>. Only two package
types are special: <span class="extract"><span class="extract-syntax">_code</span></span>, which as we have seen marks that a package is a
function, and <span class="extract"><span class="extract-syntax">_linkage</span></span>, which is used only for a special package called
<span class="extract"><span class="extract-syntax">connectors</span></span>. Stand-alone programs never contain that package: see
<a href="../bytecode-module/index.html" class="internal">bytecode</a> for an explanation of what it is for.
</p>

<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;7. </b><span class="extract"><span class="extract-syntax">primitive !PRIMITIVE SIGNATURE</span></span> declares that a primitive invocation of
this name and signature can be used in the program. Primitives occur only
inside of functions, where they are "invoked", and they are operations
sufficiently basic that they cannot themselves be written as other Inter
functions. For example, in <span class="extract"><span class="extract-syntax">Hello</span></span> we saw:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">            </span><span class="reserved-syntax">inv</span><span class="plain-syntax"> </span><span class="function-syntax">!print</span>
<span class="plain-syntax">                </span><span class="reserved-syntax">val</span><span class="plain-syntax"> </span><span class="string-syntax">"Hello, world.\n"</span>
</pre>
<p class="commentary">This is an invocation of the primitive <span class="extract"><span class="extract-syntax">!print</span></span>, which prints text. The
"signature" of this is <span class="extract"><span class="extract-syntax">val -&gt; void</span></span>, meaning that it expects to have one
argument, a value, and produces no result.
</p>

<p class="commentary">The declarations for the two primitives in <span class="extract"><span class="extract-syntax">Hello</span></span> would look like this:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">primitive</span><span class="plain-syntax"> </span><span class="function-syntax">!enableprinting</span><span class="plain-syntax"> </span><span class="reserved-syntax">void</span><span class="plain-syntax"> -&gt; </span><span class="reserved-syntax">void</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">primitive</span><span class="plain-syntax"> </span><span class="function-syntax">!print</span><span class="plain-syntax"> </span><span class="reserved-syntax">val</span><span class="plain-syntax"> -&gt; </span><span class="reserved-syntax">void</span>
</pre>
<p class="commentary">But once again they do not need to be given, because they are part of the
standard set of Inter primitives supported by <a href="index.html" class="internal">inter</a>. So these definitions
are implicitly made as needed.
</p>

<p class="commentary">In principle, though, the program could create entirely novel primitives:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">primitive</span><span class="plain-syntax"> </span><span class="function-syntax">!flytoarabia</span><span class="plain-syntax"> </span><span class="reserved-syntax">val</span><span class="plain-syntax"> </span><span class="reserved-syntax">val</span><span class="plain-syntax"> </span><span class="reserved-syntax">val</span><span class="plain-syntax"> -&gt; </span><span class="reserved-syntax">void</span>
</pre>
<p class="commentary">And this will work perfectly well... except that <a href="index.html" class="internal">inter</a> will not be able
to code-generate from the result without modification, because it won't know
how to fly to Arabia. So in practice, unless you are experimenting with
modified versions of Inter, do not use the <span class="extract"><span class="extract-syntax">primitive</span></span> construct at all.
</p>

<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>&#167;8. </b>The declaration line for a package begins at the level of indentation of
the package's owner. For <span class="extract"><span class="extract-syntax">main</span></span>, it should be unindented, and this is the
only package allowed to appear at the top level: all other packages should
be inside <span class="extract"><span class="extract-syntax">main</span></span> in some way.
</p>

<p class="commentary">The contents of the package are then one tab stop in from the declaration. Thus:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">package</span><span class="plain-syntax"> main _plain</span>
<span class="plain-syntax">        ...</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">package</span><span class="plain-syntax"> m1_RBLK1 _code</span>
<span class="plain-syntax">            ...</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">package</span><span class="plain-syntax"> m1_RBLK2 _code</span>
<span class="plain-syntax">            ...</span>
</pre>
<p class="commentary">Here, <span class="extract"><span class="extract-syntax">main</span></span> contains two sub-packages, <span class="extract"><span class="extract-syntax">m1_RBLK1</span></span> and <span class="extract"><span class="extract-syntax">m1_RBLK2</span></span>, and
indentation is used to show which package a statement belongs to.
</p>

<p class="commentary">Packages of any type can freely be created inside packages of any other type,
except that <span class="extract"><span class="extract-syntax">_code</span></span> packages cannot have subpackages. So this hypothetical bit of
Inter is illegal:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">package</span><span class="plain-syntax"> my_function _code</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">package</span><span class="plain-syntax"> inner_part _code</span>
<span class="plain-syntax">            ...</span>
<span class="plain-syntax">        ...</span>
</pre>
<p class="commentary">Here, <span class="extract"><span class="extract-syntax">inner_part</span></span> cannot be made a subpackage of <span class="extract"><span class="extract-syntax">my_function</span></span> because <span class="extract"><span class="extract-syntax">_code</span></span>
packages have no subpackages.
</p>

<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>&#167;9. </b>The remaining statements to cover fall into two categories.
</p>

<ul class="items"><li>&#9679; Those used outside functions, i.e., packages of type <span class="extract"><span class="extract-syntax">_code</span></span>, are covered in
<a href="M-dpiti.html" class="internal">Data Packages in Textual Inter</a>.
</li><li>&#9679; Those used in functions, i.e., packages of type <span class="extract"><span class="extract-syntax">_code</span></span>, are covered in
<a href="M-cpiti.html" class="internal">Code Packages in Textual Inter</a>.
</li></ul>
<nav role="progress"><div class="progresscontainer">
    <ul class="progressbar"><li class="progressprev"><a href="M-ui.html">&#10094;</a></li><li class="progresscurrentchapter">M</li><li class="progresssection"><a href="M-ui.html">ui</a></li><li class="progresscurrent">ti</li><li class="progresssection"><a href="M-dpiti.html">dpiti</a></li><li class="progresssection"><a href="M-cpiti.html">cpiti</a></li><li class="progresssection"><a href="M-ip.html">ip</a></li><li class="progresssection"><a href="M-ia.html">ia</a></li><li class="progresssection"><a href="M-io.html">io</a></li><li class="progresssection"><a href="M-pas.html">pas</a></li><li class="progresssection"><a href="M-rc.html">rc</a></li><li class="progresschapter"><a href="1-mn.html">1</a></li><li class="progressnext"><a href="M-dpiti.html">&#10095;</a></li></ul></div>
</nav><!-- End of weave -->

		</main>
	</body>
</html>

